---
title: 페이지
description: Astro 페이지 소개
i18nReady: true
---

import ReadMore from '~/components/ReadMore.astro';
import Since from '~/components/Since.astro'

**페이지**는 Astro 프로젝트의 하위 디렉터리인 `src/pages/`에 저장된 파일입니다. 이 파일들은 웹사이트의 모든 페이지에 대해 라우팅, 데이터 불러오기, 전체 페이지 레이아웃 처리를 수행합니다.

## 지원되는 페이지 파일

Astro는 `src/pages/` 디렉터리에서 다음 파일 유형을 지원합니다:

- [`.astro`](#astro-페이지)
- [`.md`](#markdownmdx-페이지)
- `.mdx` ([MDX 통합이 설치된 경우](/ko/guides/integrations-guide/mdx/#설치))
- [`.html`](#html-페이지)
- `.js`/`.ts` ([엔드포인트](/ko/guides/endpoints/)로 사용)

## 파일 기반 라우팅

Astro는 **파일 기반 라우팅**이라는 라우팅 전략을 활용합니다. `src/pages/` 디렉터리의 각 파일은 파일 경로에 해당하는 엔드포인트가 됩니다.

단일 파일은 [동적 라우팅](/ko/guides/routing/#동적-경로)을 사용하여 여러 페이지를 생성할 수도 있습니다. 이를 통해 콘텐츠가 [콘텐츠 컬렉션](/ko/guides/content-collections/)이나 [CMS](/ko/guides/cms/)와 같이 `/pages/` 디렉터리 외부에 있는 경우에도 페이지를 생성할 수 있습니다.

<ReadMore>[Astro 라우팅](/ko/guides/routing/)에서 더 자세히 알아보세요.</ReadMore>

### 페이지 간 링크

Astro 페이지에 표준 HTML[`<a>` 요소](https://developer.mozilla.org/ko/docs/Web/HTML/Element/a)를 작성하여 여러분의 사이트의 서로 다른 페이지를 연결하세요. 파일에 대한 상대 경로가 아닌 **루트 도메인에 대해 상대적인 URL 경로**를 링크로 사용하세요.

예를 들어, `example.com`의 다른 페이지에서 `https://example.com/authors/sonali/`로 링크하려면 다음을 코드를 사용하세요.

```astro title="src/pages/index.astro"
 <a href="/authors/sonali/">Sonali에 대해</a> 자세히 알아보세요.
```

## Astro 페이지

Astro 페이지는 `.astro` 파일 확장자를 사용하며 [Astro 컴포넌트](/ko/basics/astro-components/)와 동일한 기능을 지원합니다.

```astro title="src/pages/index.astro"
---
---
<html lang="ko">
  <head>
    <title>나의 홈페이지</title>
  </head>
  <body>
    <h1>제 웹사이트에 오신 것을 환영합니다!</h1>
  </body>
</html>
```

페이지는 전체 HTML 문서를 생성해야 합니다. 명시적으로 포함되지 않았다면, Astro는 기본적으로 `src/pages/` 디렉터리에 있는 모든 `.astro` 컴포넌트에 필수 `<!DOCTYPE html>` 선언과 `<head>` 콘텐츠를 추가합니다. [부분적](#부분적-페이지) 페이지로 표시하여 컴포넌트별로 이 동작을 해제할 수 있습니다.

모든 페이지에서 동일한 HTML 요소가 반복되는 것을 방지하려면 공통 `<head>` 및 `<body>` 요소를 자체 [레이아웃 컴포넌트](/ko/basics/layouts/)로 이동할 수 있습니다. 원하는 만큼 레이아웃 컴포넌트를 사용할 수 있습니다.

```astro {3} /</?MySiteLayout>/
---
// src/pages/index.astro
import MySiteLayout from '../layouts/MySiteLayout.astro';
---
<MySiteLayout>
  <p>레이아웃으로 감싼 페이지 콘텐츠입니다!</p>
</MySiteLayout>
```

<ReadMore>Astro의 [레이아웃 컴포넌트](/ko/basics/layouts/)에 대해 자세히 알아보세요.</ReadMore>

## Markdown/MDX 페이지

또한, Astro는 `src/pages/` 디렉터리의 모든 Markdown (`.md`) 파일을 최종 웹사이트의 페이지로 처리합니다. [MDX 통합이 설치된 경우](/ko/guides/integrations-guide/mdx/#설치), MDX (`.mdx`) 파일도 동일한 방식으로 처리됩니다. 이는 일반적으로 블로그 게시물 및 문서와 같이 텍스트가 많은 페이지에 사용됩니다.

`src/content/` 디렉터리의 [Markdown 또는 MDX 콘텐츠 컬렉션](/ko/guides/content-collections/)을 사용하여 [페이지를 동적으로 생성](/ko/guides/routing/#동적-경로)할 수 있습니다.

페이지 레이아웃은 특히 [Markdown 파일](#markdownmdx-페이지)에 유용합니다. Markdown 파일은 특수 `layout` 프런트매터 속성을 사용하여 Markdown 콘텐츠를 `<html>...</html>` 페이지로 감싸는 [레이아웃 컴포넌트](/ko/basics/layouts/)를 지정할 수 있습니다.

```md {3}
---
# Example: src/pages/page.md
layout: '../layouts/MySiteLayout.astro'
title: '나의 Markdown 페이지'
---
# 제목

이 페이지는 **Markdown**으로 작성되었습니다.
```

<ReadMore>Astro의 [Markdown](/ko/guides/markdown-content/)에 대해 자세히 알아보세요.</ReadMore>

## HTML 페이지

`.html` 파일 확장자를 가진 파일은 `src/pages/` 디렉터리에 배치할 수 있으며 사이트의 페이지로 직접 사용할 수 있습니다. Astro의 일부 주요 기능은 [HTML 컴포넌트](/ko/basics/astro-components/#html-컴포넌트)에서 지원되지 않습니다.

## 사용자 정의 404 오류 페이지

사용자 정의 404 오류 페이지는 `/src/pages` 디렉터리에 `404.astro` 또는 `404.md` 파일로 만들 수 있습니다.

이를 통해 `404.html` 페이지가 빌드됩니다. 대부분의 [배포 서비스](/ko/guides/deploy/)가 이 파일을 찾아서 사용합니다.

## 부분적 페이지

<p><Since v="3.4.0" /></p>

:::caution
부분적 페이지는 [htmx](https://htmx.org/) 또는 [Unpoly](https://unpoly.com/)와 같은 프런트엔드 라이브러리와 함께 사용하기 위한 것입니다. 낮은 수준의 프런트엔드 JavaScript 작성에 능숙한 경우에도 사용할 수 있습니다. 이러한 이유로 이는 고급 기능입니다.

또한 컴포넌트에 범위가 지정된 스타일이나 스크립트가 포함된 경우에는 사용할 수 없습니다. 이러한 요소는 HTML 출력에서 ​​제거되기 때문입니다. 범위가 지정된 스타일이 필요한 경우, 콘텐츠를 head에 병합하는 방법을 알고 있는 프런트엔드 라이브러리와 함께 부분적 페이지가 아닌 일반 페이지를 사용하는 것이 좋습니다.
:::

부분적 페이지는 전체 페이지로 렌더링되지 않는 `src/pages/` 디렉터리에 있는 페이지 컴포넌트입니다.

이 폴더 외부에 있는 컴포넌트와 마찬가지로 이러한 파일에는 `<!DOCTYPE html>` 선언이나 범위가 지정된 스타일 및 스크립트와 같은 `<head>` 콘텐츠가 자동으로 포함되지 않습니다.

그러나 특별한 `src/pages/` 디렉터리에 존재하기 때문에, 생성된 HTML은 해당 파일 경로에 해당하는 URL에서 사용할 수 있습니다. 이를 통해 렌더링 라이브러리(예: htmx, Stimulus, jQuery)가 클라이언트에서 URL에 접근할 수 있으며, 브라우저 새로 고침이나 페이지 탐색 없이 페이지에서 동적으로 HTML 섹션을 불러올 수 있습니다.

부분적 페이지를 렌더링 라이브러리와 함께 사용하여 Astro에서 동적 콘텐츠를 만들기 위한 [Astro 아일랜드](/ko/concepts/islands/) 및 [`<script>` 태그](/ko/guides/client-side-scripts/)의 대안을 제공합니다.

값을 내보낼 수 있는 페이지 파일(예: `.astro` , `.mdx`)은 부분적 페이지로 표시될 수 있습니다.

다음과 같이 내보내기를 추가하여 `src/pages/` 디렉터리의 파일을 부분적 페이지로 구성하세요.

```astro title="src/pages/partial.astro" ins={2}
---
export const partial = true;
---

<li>부분적 페이지입니다!</li>
```

`export const partial`은 정적으로 식별 가능해야 합니다. 다음과 같은 값을 가질 수 있습니다.

- 불리언 값인 __`true`__.
- `import.meta.env.USE_PARTIALS`와 같은 import.meta.env를 사용하는 환경 변수.

### 라이브러리와 함께 사용

 부분적 페이지는 [htmx](https://htmx.org/)와 같은 라이브러리를 사용하여 페이지 섹션을 동적으로 업데이트하는 데 사용됩니다.

 다음 예시는 부분적 페이지의 URL로 설정된 `hx-post` 속성을 보여줍니다. 부분적 페이지의 콘텐츠는 이 페이지의 대상 HTML 요소를 업데이트하는 데 사용됩니다.

```astro title="src/pages/index.astro" 'hx-post="/partials/clicked/"'
<html>
  <head>
    <title>나의 페이지</title>
    <script src="https://unpkg.com/htmx.org@1.9.6"
      integrity="sha384-FhXw7b6AlE/jyjlZH5iHa/tTe9EpJ1Y55RjcgPbjeWMskSxZt1v9qkxLJWNJaGni"
      crossorigin="anonymous"></script>
  </head>
</html>
<section>
  <div id="parent-div">대상 요소</div>

  <button hx-post="/partials/clicked/"
    hx-trigger="click"
    hx-target="#parent-div"
    hx-swap="innerHTML"
  >
      클릭하세요!
  </button>
</section>
```

`.astro` 부분적 페이지는 해당 파일 경로에 존재해야 하며, 페이지를 부분적 페이지로 정의하는 내보내기를 포함해야 합니다.

```astro title="src/pages/partials/clicked.astro" {2}
---
export const partial = true;
---
<div>이미 클릭되었습니다!</div>
```

htmx 사용에 대한 자세한 내용은 [htmx 문서](https://htmx.org/docs/)를 참조하세요.